---
id: share-open
title: Share.open
---

The open() method allows a user to share a premade message via a social medium they choose. In other words, code specifies the message that will be sent and the user chooses to whom and the social medium through which the message will be sent. This shared message may contain text, one or more files, or both.

Calling this method will return a promise that will fulfill or be rejected as soon as ther user successfully open the share action sheet or cancel/fail. Because of that, you will need to handle the rejection while necessary.

Using a promise implementation:

```js
Share.open(options)
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    err && console.log(err);
  });
```

Or with `async/await`:

```js
const fun = async () => {
  const shareResponse = await Share.open(options);
};
```

\*Keep in mind that using a `async/await` approach you will still need to handle the error response.

## Supported Options

You can customize the call to `Share.open` passing the following parameters:

| Name                  |     Type      | Description                                                                                                                                                    | Optional | Android | iOS | Windows |
| :-------------------- | :-----------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ | :-- | :------ |
| message               |    string     | Message sent to the share activity                                                                                                                             | ✅       | ✅      | ✅  | ❓      |
| title                 |    string     | Title sent to the share activity                                                                                                                               | ✅       | ✅      | ✅  | ❓      |
| url                   |    string     | URL you want to share (only support base64 string in iOS & Android).                                                                                           | ✅       | ✅      | ✅  | ❓      |
| urls                  | Array[string] | Array of base64 string you want to share.                                                                                                                      | ✅       | ✅      | ✅  | ❓      |
| type                  |    string     | File mime type                                                                                                                                                 | ✅       | ✅      | ✅  | ❓      |
| subject               |    string     | Subject sent when sharing to email                                                                                                                             | ✅       | ✅      | ✅  | ❓      |
| email                 |    string     | Email of addressee                                                                                                                                             | ✅       | ✅      | ✅  | ❓      |
| recipient             |    string     | Phone number of SMS recipient                                                                                                                                  | ✅       | ✅      | 🚫  | 🚫      |
| excludedActivityTypes | Array[string] | Activity types that won't show in the Share dialog                                                                                                             | ✅       | ✅      | ✅  | ❓      |
| failOnCancel          |    boolean    | (defaults to true) Specifies whether promise should reject if user cancels share dialog                                                                        | ✅       | ✅      | ✅  | ❓      |
| showAppsToView        |    boolean    | only android                                                                                                                                                   | ✅       | ✅      | 🚫  | ❓      |
| filename              |    string     | Filename for base64 in iOS & Android                                                                                                                           | ✅       | ✅      | ✅  | ❓      |
| saveToFiles           |    boolean    | Open only `Files` app (supports only urls (base64 string or path), requires iOS 11 or later)                                                                   | ✅       | 🚫      | ✅  | ❓      |
| filenames             | Array[string] | Array of filename for base64 urls array in Android & iOS                                                                                                       | ✅       | ✅      | ✅  | ❓      |
| activityItemSources   | Array[Object] | Array of activity item sources. Each items should conform to [ActivityItemSource](#activityitemsource) specification. [Example](#example-activityitemsources). | ✅       | 🚫      | ✅  | ❓      |
| useInternalStorage    |    boolean    | Store the temporary file in the internal storage cache (Android only)                                                                                          | ✅       | ✅      | 🚫  | 🚫      |
| isNewTask             |    boolean    | Open intent as a new task. "failOnCancel" will not work.                                                                                                       | ✅       | ✅      | 🚫  | ❓      |

## Sharing a base64 file format

When sharing a `base64` file, you will need to follow the format below:

`url: "data:<data_type>/<file_extension>;base64,<base64_data>"`

**Note:** If your application requires the ability to share `base64` files on Android, you need to add

```xml
<!-- required for react-native-share base64 sharing -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
```

to your application's `AndroidManifest.xml` file as per the example project.

## Sharing a file directly

When sharing a local file directly, you can use the following format:

`url: "file://<file_path>"`

## ActivityItemSources (iOS only)

In order to share different data according to activities or to customize the share sheet, you can provide the data by using `activityItemSources` .

See [here](https://developer.apple.com/documentation/uikit/uiactivityitemsource) for more information about UIActivityItemSource.

#### Example ActivityItemSources

```jsx
import { Platform } from 'react-native';
import Share from 'react-native-share';

const url = 'https://awesome.contents.com/';
const title = 'Awesome Contents';
const message = 'Please check this out.';
const icon = 'data:<data_type>/<file_extension>;base64,<base64_data>';
const options = Platform.select({
  ios: {
    activityItemSources: [
      {
        // For sharing url with custom title.
        placeholderItem: { type: 'url', content: url },
        item: {
          default: { type: 'url', content: url },
        },
        subject: {
          default: title,
        },
        linkMetadata: { originalUrl: url, url, title },
      },
      {
        // For sharing text.
        placeholderItem: { type: 'text', content: message },
        item: {
          default: { type: 'text', content: message },
          message: null, // Specify no text to share via Messages app.
        },
        linkMetadata: {
          // For showing app icon on share preview.
          title: message,
        },
      },
      {
        // For using custom icon instead of default text icon at share preview when sharing with message.
        placeholderItem: {
          type: 'url',
          content: icon,
        },
        item: {
          default: {
            type: 'text',
            content: `${message} ${url}`,
          },
        },
        linkMetadata: {
          title: message,
          icon: icon,
        },
      },
    ],
  },
  default: {
    title,
    subject: title,
    message: `${message} ${url}`,
  },
});

Share.open(options);
```

### ActivityItemSource

Structure used when the option `activityItemSources` is being used:

| Name               |  Type  | Description                                                                                                                                                                                                                                                                                                                               |
| :----------------- | :----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| placeholderItem    | Object | An object to use as a placeholder for the actual data. This should comform to [ActivityItem](#activityitem) type.                                                                                                                                                                                                                         |
| item               | Object | An object that contains the final data object to be acted on for each [activity types](#activitytype). This should be `{ [ActivityType]: ?ActivityItem }` .                                                                                                                                                                               |
| subject            | Object | (optional) An object that contains a string to use as the contents of the subject field for each [activity types](#activitytype). This should be `{ [ActivityType]: string }` .                                                                                                                                                           |
| dataTypeIdentifier | Object | (optional) An object that contains the UTI for the item for each [activity types](#activitytype). This should be `{ [ActivityType]: string }` . See [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/understanding_utis/understand_utis_intro/understand_utis_intro.html) for more information. |
| thumbnailImage     | Object | (optional) An object that contains the URL to the image to use as a preview for the item for each [activity types](#activitytype). This should be `{ [ActivityType]: string }` . The URL should begin with `data:` and contain the data as base 64 encoded string.                                                                        |
| linkMetadata       | Object | (optional) An object that contains the metadata about a URL, including its title, icon, images, and video. See [LinkMetadata](#linkmetadata).                                                                                                                                                                                             |

#### ActivityType

- `addToReadingList`
- `airDrop`
- `assignToContact`
- `copyToPasteBoard`
- `mail`
- `message`
- `openInIBooks` (iOS 9+)
- `postToFacebook`
- `postToFlickr`
- `postToTencentWeibo`
- `postToTwitter`
- `postToVimeo`
- `postToWeibo`
- `print`
- `saveToCameraRoll`
- `markupAsPDF` (iOS 11+)

Also you can use `default` in order to specify default behavior.

### ActivityItem

| Name    |      Type       | Description                                                                                                                   |
| :------ | :-------------: | :---------------------------------------------------------------------------------------------------------------------------- |
| type    | `text` \| `url` | Type of the content.                                                                                                          |
| content |     string      | Text or URL to share. You can specify image with URL that begins with `data` and contains the data as base 64 encoded string. |

### LinkMetadata

| Name           |  Type  | Description                                                                              |
| :------------- | :----: | :--------------------------------------------------------------------------------------- |
| originalUrl    | string | (optional) The original URL of the metadata request.                                     |
| url            | string | (optional) The URL that returns the metadata, taking server-side redirects into account. |
| title          | string | (optional) A representative title for the URL.                                           |
| icon           | string | (optional) A URL of the file corresponding to a representative icon for the URL.         |
| image          | string | (optional) A URL of the file corresponding to a representative image for the URL.        |
| remoteVideoUrl | string | (optional) A remote URL corresponding to a representative video for the URL.             |
| video          | string | (optional) A URL of the file corresponding to a representative video for the URL.        |

## LSApplicationQueriesSchemes (iOS only)

If you want to share Whatsapp, Mailto or some applications on iOS, you should write [`LSApplicationQueriesSchemes`](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/plist/info/LSApplicationQueriesSchemes) in info.plist:

```xml
  <key>LSApplicationQueriesSchemes</key>
  <array>
    <string>whatsapp</string>
    <string>mailto</string>
  </array>
```

Also, to save photos your gallery you will need setting the following permission on your `Info.plist`:

```xml
  <key>NSPhotoLibraryAddUsageDescription</key>
  <string>$(PRODUCT_NAME) wants to save photos</string>
```
